# JSON命令

# JSON.ARRAPPEND

# 语法

JSON.ARRAPPEND key path value [value ...]

# 描述

将 JSON 值追加到指定路径的数组中最后一个元素之后。

# 参数

key

键名。

path

要匹配的 JSONPath 路径。

value

要追加到一个或多个数组中的一个或多个值。

# 示例

> JSON.SET item:1 $ '{"name":"Noise-cancelling Bluetooth headphones","description":"Wireless Bluetooth headphones with noise-cancelling technology","connection":{"wireless":true,"type":"Bluetooth"},"price":99.98,"stock":25,"colors":["black","silver"]}'
OK

> JSON.ARRAPPEND item:1 $.colors '"blue"'
1) (integer) 3

> JSON.GET item:1 $.colors
"[[\"black\",\"silver\",\"blue\"]]"

# JSON.ARRINDEX

# 语法

JSON.ARRINDEX key path value [start [stop]]

# 描述

在数组中查找 JSON 值的首次出现位置

# 参数

key

键名。

path

要匹配的 JSONPath 路径。

value

要追加到一个或多个数组中的一个或多个值。

start

是要在搜索的数组切片中指定的起始值（包含该值）。默认值为 0。

stop

用于指定搜索数组切片时的结束索引（不包含该位置），包含最后一个元素。默认值为 0。负数则代表从末尾倒数。

# 示例

> JSON.SET item:1 $ '{"name":"Noise-cancelling Bluetooth headphones","description":"Wireless Bluetooth headphones with noise-cancelling technology","connection":{"wireless":true,"type":"Bluetooth"},"price":99.98,"stock":25,"colors":["black","silver"]}'
OK

> JSON.ARRAPPEND item:1 $.colors '"blue"'
1) (integer) 3

> JSON.GET item:1
"{\"name\":\"Noise-cancelling Bluetooth headphones\",\"description\":\"Wireless Bluetooth headphones with noise-cancelling technology\",\"connection\":{\"wireless\":true,\"type\":\"Bluetooth\"},\"price\":99.98,\"stock\":25,\"colors\":[\"black\",\"silver\",\"blue\"]}"

> JSON.GET item:1 '$.colors[*]'
"[\"black\",\"silver\",\"blue\"]"

# JSON.ARRINSERT

# 语法

JSON.ARRINSERT key path index value [value ...]

# 描述

将 JSON 值插入到指定路径的数组中，位置在索引之前（原有元素向右移动）。

# 参数

key

键名。

value

要追加到一个或多个数组中的一个或多个值。

index

指想在数组中插入值的具体位置。该索引必须在数组的有效范围内。在索引 0 处插入，表示将值添加到数组的最前面。如果索引值为负数，则从数组的末尾开始倒数计算。

path

要匹配的 JSONPath 路径。默认值为根节点 $

# 示例

> JSON.SET item:1 $ '{"name":"Noise-cancelling Bluetooth headphones","description":"Wireless Bluetooth headphones with noise-cancelling technology","connection":{"wireless":true,"type":"Bluetooth"},"price":99.98,"stock":25,"colors":["black","silver"]}'
OK

> JSON.ARRAPPEND item:1 $.colors '"blue"'
1) (integer) 3

> JSON.GET item:1
"{\"name\":\"Noise-cancelling Bluetooth headphones\",\"description\":\"Wireless Bluetooth headphones with noise-cancelling technology\",\"connection\":{\"wireless\":true,\"type\":\"Bluetooth\"},\"price\":99.98,\"stock\":25,\"colors\":[\"black\",\"silver\",\"blue\"]}"

> JSON.GET item:1 '$.colors[*]'
"[\"black\",\"silver\",\"blue\"]"

# JSON.ARRLEN

# 语法

JSON.ARRLEN key [path]

# 描述

报告 key 中指定路径（path）下 JSON 数组的长度。

# 参数

key

键名。

path

要匹配的 JSONPath 路径。

# 示例

> JSON.SET item:2 $ '{"name":"Wireless earbuds","description":"Wireless Bluetooth in-ear headphones","connection":{"wireless":true,"type":"Bluetooth"},"price":64.99,"stock":17,"colors":["black","white"], "max_level":[80, 100, 120]}'
OK

> JSON.ARRLEN item:2 '$.[*]'
1) (nil)
2) (nil)
3) (nil)
4) (nil)
5) (nil)
6) (integer) 2
7) (integer) 3

> JSON.ARRLEN item:2 '$..max_level'
1) (integer) 3

> JSON.GET item:2 '$..max_level'
"[[80,100,120]]"

# JSON.ARRPOP

# 语法

JSON.ARRPOP key [path [index]]

# 描述

移除并返回数组中指定索引位置的元素。

# 参数

key

键名。

path

要匹配的 JSONPath 路径。

index

指定数组中开始弹出元素的起始位置。默认为 -1（即最后一个元素）。越界索引会自动向两端取整。对空数组执行弹出操作返回 null。

# 示例

> JSON.SET key $ '[{"name":"Healthy headphones","description":"Wireless Bluetooth headphones with noise-cancelling technology","connection":{"wireless":true,"type":"Bluetooth"},"price":99.98,"stock":25,"colors":["black","silver"],"max_level":[60,70,80]},{"name":"Noisy headphones","description":"Wireless Bluetooth headphones with noise-cancelling technology","connection":{"wireless":true,"type":"Bluetooth"},"price":99.98,"stock":25,"colors":["black","silver"],"max_level":[80,90,100,120]}]'
OK

> JSON.GET key $.[1].max_level
"[[80,90,100,120]]"

> JSON.ARRPOP key $.[1].max_level 0
1) "80"

> JSON.GET key $.[1].max_level
"[[90,100,120]]"

> JSON.ARRINSERT key $.[1].max_level 0 85
1) (integer) 4

> JSON.GET key $.[1].max_level
"[[85,90,100,120]]"

# JSON.ARRTRIM

# 语法

JSON.ARRTRIM key path start stop

# 描述

裁剪数组，仅保留指定闭区间范围内的元素。

# 参数

key

键名。

path

要匹配的 JSONPath 路径。

start

要保留的第一个元素的索引（之前的元素会被裁剪掉）。默认值为 0。

stop

包含该元素本身。默认值为 0。负数值会被解析为从数组末尾开始计算。### 示例

> JSON.SET key $
"[{\"name\":\"Healthy headphones\",\"description\":\"Wireless Bluetooth headphones with noise-cancelling technology\",\"connection\":{\"wireless\":true,\"type\":\"Bluetooth\"},\"price\":99.98,\"stock\":25,\"colors\":[\"black\",\"silver\"],\"max_level\":[60,70,80]},{\"name\":\"Noisy headphones\",\"description\":\"Wireless Bluetooth headphones with noise-cancelling technology\",\"connection\":{\"wireless\":true,\"type\":\"Bluetooth\"},\"price\":99.98,\"stock\":25,\"colors\":[\"black\",\"silver\"],\"max_level\":[85,90,100,120]}]"
OK

> JSON.ARRAPPEND key $.[1].max_level 140 160 180 200 220 240 260 280
1) (integer) 12

> JSON.GET key $.[1].max_level
"[[85,90,100,120,140,160,180,200,220,240,260,280]]"

> JSON.ARRTRIM key $.[1].max_level 4 8
1) (integer) 5

> JSON.GET key $.[1].max_level
"[[140,160,180,200,220]]"

# JSON.CLEAR

# 语法

JSON.CLEAR key [path]JSON.CLEAR key [path]

# 描述

清空容器类型的值（数组/对象），并将数值类型的值设为 0。

# 参数

key

键名。

path

用 JSONPath 来定位，默认找根节点 $

# 示例

> JSON.SET doc $ '{"obj":{"a":1, "b":2}, "arr":[1,2,3], "str": "foo", "bool": true, "int": 42, "float": 3.14}'
OK

> JSON.CLEAR doc $.*
(integer) 4

> JSON.GET doc $
"[{\"obj\":{},\"arr\":[],\"str\":\"foo\",\"bool\":true,\"int\":0,\"float\":0}]"

# JSON.DEBUG HELP

# 语法

JSON.DEBUG HELP

# 描述

返回关于 JSON.DEBUG 命令的有用信息。

# JSON.DEBUG MEMORY

# 语法

JSON.DEBUG MEMORY key [path]

# 描述

以字节为单位报告某个值的内存占用

# 参数

key

键名。

path

用 JSONPath 来定位，默认找根节点 $

# 示例

> JSON.SET item:2 $ '{"name":"Wireless earbuds","description":"Wireless Bluetooth in-ear headphones","connection":{"wireless":true,"type":"Bluetooth"},"price":64.99,"stock":17,"colors":["black","white"], "max_level":[80, 100, 120]}'
OK

> JSON.DEBUG MEMORY item:2
(integer) 573

# JSON.DEBUG

# 语法

JSON.DEBUG

# 描述

用于调试相关任务的容器命令。

# JSON.DEL

# 语法

JSON.DEL key [path]

# 描述

删除一个值

# 参数

key

键名。

path

用 JSONPath 来定位，默认找根节点 $

# 示例

> JSON.SET doc $ '{"a": 1, "nested": {"a": 2, "b": 3}}'
OK

> JSON.DEL doc $..a
(integer) 2

> JSON.GET doc $
"[{\"nested\":{\"b\":3}}]"

> JSON.SET doc $ '{"a": 1}'
OK
> JSON.DEL doc $.a
(integer) 1
> EXISTS doc
(integer) 0
---

# JSON.FORGET

# 语法

JSON.FORGET key [path]

# 描述

当路径解析为单个值时，时间复杂度为 O(N)，其中 N 为被删除值的大小；当路径解析为多个值时，时间复杂度为 O(N)，其中 N 为键（key）的大小。

# JSON.GET

# 语法

JSON.GET key [INDENT indent] [NEWLINE newline] [SPACE space] [path
  [path ...]]

# 描述

返回指定路径的值，结果为 JSON 序列化形式。

# 参数

key

键名。

path

用 JSONPath 来定位，默认找根节点 $

# 示例

> JSON.SET doc $ '{"a":2, "b": 3, "nested": {"a": 4, "b": null}}'
OK

>  JSON.GET doc $..b
"[3,null]"

> JSON.GET doc ..a $..b
"{\"$..b\":[3,null],\"..a\":[2,4]}"

# JSON.MERGE

# 语法

JSON.MERGE key path value

# 描述

将给定的 JSON 值合并到匹配的路径中。

# 参数

key

键名。

path

用 JSONPath 来定位，默认找根节点 $

value

要在指定路径处合并的 JSON 值

# 示例

> JSON.SET doc $ '{"a":2}'
OK
> JSON.MERGE doc $.b '8'
OK
> JSON.GET doc $
"[{\"a\":2,\"b\":8}]"

> JSON.SET doc $ '{"a":2}'
OK
> JSON.MERGE doc $.a '3'
OK
> JSON.GET doc $
"[{\"a\":3}]"

> JSON.SET doc $ '{"a":2}'
OK
> JSON.MERGE doc $ '{"a":null}'
OK
> JSON.GET doc $
"[{}]"

> JSON.SET doc $ '{"a":[2,4,6,8]}'
OK
> JSON.MERGE doc $.a '[10,12]'
OK
> JSON.GET doc $
"[{\"a\":[10,12]}]"

> JSON.SET doc $ '{"f1": {"a":1}, "f2":{"a":2}}'
OK
> JSON.GET doc
"{\"f1\":{\"a\":1},\"f2\":{\"a\":2}}"
> JSON.MERGE doc $ '{"f1": null, "f2":{"a":3, "b":4}, "f3":[2,4,6]}'
OK
> JSON.GET doc
"{\"f2\":{\"a\":3,\"b\":4},\"f3\":[2,4,6]}"

# JSON.MGET

# 语法

JSON.MGET key [key ...] path

# 描述

根据多个键（key）参数，返回指定路径下的值

# 参数

key

键名。

path

需使用 JSONPath 来指定。如果路径不存在，则返回 null。

# 示例

> JSON.SET doc1 $ '{"a":1, "b": 2, "nested": {"a": 3}, "c": null}'
OK
> JSON.SET doc2 $ '{"a":4, "b": 5, "nested": {"a": 6}, "c": null}'
OK

> JSON.MGET doc1 doc2 $..a
1) "[1,3]"
2) "[4,6]"

# JSON.MSET

# 语法

JSON.MSET key path value [key path value ...]

# 描述

按指定的键-路径-值三元组，设置或更新 JSON 值

# 参数

key

键名。

path

需要指定 JSONPath（路径）。对于新建的 Redis 键，该路径必须是根路径

value

要在指定路径处合并的 JSON 值

# 示例

> JSON.MSET doc1 $ '{"a":1}' doc2 $ '{"f":{"a":2}}' doc3 $ '{"f1":{"a":0},"f2":{"a":0}}'
OK
> JSON.MSET doc1 $ '{"a":2}' doc2 $.f.a '3' doc3 $ '{"f1":{"a":1},"f2":{"a":2}}'
OK
> JSON.GET doc1 $
"[{\"a\":2}]"
> JSON.GET doc2 $
"[{\"f\":{\"a\":3}}]"
> JSON.GET doc3
"{\"f1\":{\"a\":1},\"f2\":{\"a\":2}}"

# JSON.NUMINCRBY

# 语法

JSON.NUMINCRBY key path value

# 描述

将路径处存储的数值增加

# 参数

key

键名。

path

用于指定的 JSONPath

value

是用于增加的数值

# 示例

> JSON.SET doc . '{"a":"b","b":[{"a":2}, {"a":5}, {"a":"c"}]}'
OK

> JSON.NUMINCRBY doc $.a 2
"[null]"

> JSON.NUMINCRBY doc $..a 2
"[null,4,7,null]"

# JSON.NUMMULTBY

# 语法

JSON.NUMMULTBY key path value

# 描述

将指定路径处存储的数值乘以

# 参数

key

键名。

path

用 JSONPath 来定位，默认找根节点 $

value

是用于增加的数值

# 示例

> JSON.SET doc . '{"a":"b","b":[{"a":2}, {"a":5}, {"a":"c"}]}'
OK
> JSON.NUMMULTBY doc $.a 2
"[null]"
> JSON.NUMMULTBY doc $..a 2
"[null,4,10,null]"

# JSON.OBJKEYS

# 语法

JSON.OBJKEYS key [path]

# 描述

返回匹配指定路径表达式的 JSON 对象键名

# 参数

key

键名。

path

根节点 $，或者任何以 $. 或 $[ 开头的字符串。该表达式会解析出 key 中所有匹配的位置。

# 示例

> JSON.SET doc $ '{"a":[3], "nested": {"a": {"b":2, "c": 1}}}'
OK
> JSON.OBJKEYS doc $..a
1) (nil)
2) 1) "b"
   2) "c"

# JSON.OBJLEN

# 语法

JSON.OBJLEN key [path]

# 描述

返回在匹配给定路径表达式的路径下，JSON 对象中键的数量

# 参数

key

键名。

path

根节点 $，或者任何以 $. 或 $[ 开头的字符串。该表达式会解析出 key 中所有匹配的位置。

# 示例

> JSON.SET doc $ '{"a":[3], "nested": {"a": {"b":2, "c": 1}}}'
OK
> JSON.OBJLEN doc $..a
1) (nil)
2) (integer) 2

# JSON.RESP

# 语法

JSON.RESP key [path]

# 描述

将 key 中的 JSON 以 Redis 序列化协议规范的形式返回。

# 参数

key

键名。

path

用于指定的 JSONPath（路径表达式）。默认值为根节点 $。该命令使用以下 JSON 到 RESP 的映射规则：

SON null 映射为 Bulk string（批量字符串）回复。
JSON 的 false 和 true 值映射为 Simple string（简单字符串）回复。
JSON 数字（number）映射为 Integer（整数）回复或 Bulk string 回复，具体取决于其类型。
JSON 字符串（string）映射为 Bulk string 回复。
JSON 数组（array）表示为 Array（数组）回复，其第一个元素是简单字符串回复 [，后面紧跟数组的各个元素。
JSON 对象（object）表示为 Array 回复，其第一个元素是简单字符串回复 {。随后的每一个条目都代表一个键值对，以包含两个元素的数组回复形式呈现（键和值均为 Bulk string 回复）。

# 示例

> JSON.SET item:2 $ '{"name":"Wireless earbuds","description":"Wireless Bluetooth in-ear headphones","connection":{"wireless":true,"type":"Bluetooth"},"price":64.99,"stock":17,"colors":["black","white"], "max_level":[80, 100, 120]}'
OK

> JSON.RESP item:2
 1) {
 2) "name"
 3) "Wireless earbuds"
 4) "description"
 5) "Wireless Bluetooth in-ear headphones"
 6) "connection"
 7) 1) {
    2) "wireless"
    3) true
    4) "type"
    5) "Bluetooth"
 8) "price"
 9) "64.989999999999995"
10) "stock"
11) (integer) 17
12) "colors"
13) 1) [
    2) "black"
    3) "white"
14) "max_level"
15) 1) [
    2) (integer) 80
    3) (integer) 100
    4) (integer) 120

# JSON.SET

# 语法

JSON.SET key path value [NX | XX] [FPHA <FP16 | BF16 | FP32 | FP64>]

# 描述

设置或替换由路径解析出的每个位置上的值

# 参数

key

键名。

path

一个 JSONPath 表达式，用于解析 JSON 文档中的零个或多个位置。文档的根节点使用 $ 或 .. 来指定。

如果路径解析到一个或多个已存在的位置，每个匹配位置上的值将被替换为指定的 value。
如果路径的最后一个标记是一个不存在的对象成员，但其父级位置存在且是一个对象，则会创建该成员并将其设置为 value。
如果路径中的任何中间元素不存在，则无法创建该路径，命令将返回 nil。”
value

是用于增加的数值

# 示例

> JSON.SET doc $ '{"a":2}'
OK
> JSON.SET doc $.a '3'
OK
> JSON.GET doc $
"[{\"a\":3}]"

> JSON.SET doc $ '{"a":2}'
OK
> JSON.SET doc $.b '8'
OK
> JSON.GET doc $
"[{\"a\":2,\"b\":8}]"

> JSON.SET doc $ '[[1,2,3,4e3],[5,6.0,7,8]]' FPHA FP16
OK
> JSON.GET doc $
"[[[1.0,2.0,3.0,4000.0],[5.0,6.0,7.0,8.0]]]"

> JSON.SET doc $ '{"f1": {"a":1}, "f2":{"a":2}}'
OK
> JSON.SET doc $..a 3
OK
> JSON.GET doc
"{\"f1\":{\"a\":3},\"f2\":{\"a\":3}}"

> JSON.SET doc $ 1
OK
> JSON.SET doc $.x.y 2
(nil)

> JSON.SET nonexistentkey $ 5 XX
(nil)
> JSON.GET nonexistentkey
(nil)

> JSON.SET nonexistentkey $.x 5
(error) ERR new objects must be created at the root

# JSON.STRAPPEND

# 语法


JSON.STRAPPEND key [path] value

# 描述

将字符串追加到匹配给定路径表达式的 JSON 字符串中

# 参数

key

键名。

path

用 JSONPath 来定位，默认找根节点 $

value

是用于增加的数值

# 示例

> JSON.SET doc $ '{"a":"foo", "nested": {"a": "hello"}, "nested2": {"a": 31}}'
OK
> JSON.STRAPPEND doc $..a '"baz"'
1) (integer) 6
2) (integer) 8
3) (nil)
> JSON.GET doc $
"[{\"a\":\"foobaz\",\"nested\":{\"a\":\"hellobaz\"},\"nested2\":{\"a\":31}}]"

# JSON.STRLEN

# 语法

JSON.STRLEN key [path]

# 描述

返回匹配给定路径表达式的 JSON 字符串的长度

# 参数

key

键名。

path

用 JSONPath 来定位，默认找根节点 $

value

是用于增加的数值

# 示例

> JSON.SET doc $ '{"a":"foo", "nested": {"a": "hello"}, "nested2": {"a": 31}}'
OK
> JSON.STRLEN doc $..a
1) (integer) 3
2) (integer) 5
3) (nil)

# JSON.TOGGLE

# 语法

JSON.TOGGLE key path

# 描述

切换（或反转）指定路径下存储的布尔值

# 参数

key

键名。

path

用 JSONPath 来定位，默认找根节点 $

# 示例

> JSON.SET doc $ '{"bool": true}'
OK

> JSON.TOGGLE doc $.bool
1) (integer) 0

> JSON.GET doc $
"[{\"bool\":false}]"

> JSON.TOGGLE doc $.bool
1) (integer) 1

> JSON.GET doc $
"[{\"bool\":true}]"

# JSON.TYPE

# 语法

JSON.TYPE key [path]

# 描述

报告该路径下 JSON 值的类型

# 参数

key

键名。

path

要指定的 JSONPath 路径。默认值为根节点 $。若键或路径不存在则返回 null。

# 示例

> JSON.SET doc $ '{"a":2, "nested": {"a": true}, "foo": "bar"}'
OK
> JSON.TYPE doc $..foo
1) "string"
> JSON.TYPE doc $..a
1) "integer"
2) "boolean"
> JSON.TYPE doc $..dummy
(empty array)

← Stream命令 Search命令 →